feat(portable): record third-party clients in the pinned capability table - #721

Why

INSTALL.md and two documentation pages asserted a bare list of Agent Plugins
"native clients" (Codex, VS Code, GitHub Copilot, Kiro, ChatGPT) with no source,
no per-client install command, and no statement of what each client actually
loads. The 21 open host-support issues (#693–#714) mostly ask the same question:
what does an existing artifact really give a given agent? That is evidence about
a reader of the artifact, not a new projection — so it belongs in the pinned
capability table the adapters already compile against, not in a second catalog.

What

• packages/agent-bundle/src/adapters/capabilities/portable-1.0.0.json gains an
  optional clients block. Each record pins one client to its own
  documentation: observed (version or doc date), tier, discovery.required
  and discovery.shadowedBy, verbatim install.commands, and a row per surface
  (manifest, skills, mcp, placeholders, hooks).
• clientCompatibilityFrom in adapters/capability-state.ts is the single
  validator over those records, beside the notice-delivery and event-route
  readers that already live there. It reuses the table's dated-evidence rule:
  supported needs dated evidence, anything less needs a dated reason, a silent
  surface is a build failure, and a tier is held to its rows (agent-plugins
  requires a manifest the client loads outright, skills requires the skill
  tree, none may claim no loaded surface at all).
• install/surface.ts prints one line per record — what it loads, its install
  command, what it does not load, and what would shadow it — replacing the
  unsourced sentence. website/plugins/generated-reference.ts renders the same
  records into the generated en/zh host matrix.
• First five records, from pinned upstream docs read 2026-09-06: Devin CLI
  (Host support: Devin CLI — native plugin manifest, portable compatibility, and versioned MCP/hook profiles #701) and OpenClaw (Host support: OpenClaw — compatible bundles first, native plugin and ClawHub skill tiers separately #702) at agent-plugins, Grok Build (Host support: Grok Build — plugin discovery, native hook semantics, and MCP configuration #700) and Qoder CLI
  (Host support: Qoder — native plugin projection with explicit CLI and IDE capability profiles #696) at skills, Antigravity (Host support: Antigravity — native plugin projection, Gemini migration boundaries, and explicit CLI/IDE contracts #714) at none.

Every unsupported surface is an explicit dated row, never a silent omission:
hooks are unavailable for all five because Agent Plugins 1.0.0 defines no
hooks and this projection emits no hooks document, and each reason names the
file that client would have needed instead.

Gate

Run on host-compat-mechanism rebased onto current origin/main (6bce18953d),
at tip fba03f7cb9:

• pnpm build — pass
• pnpm typecheck — pass
• pnpm lint — pass (1479 files, 88 rules)
• pnpm test:unit — 0 failed, 4427 passed
• pnpm docs:site:build — pass: locale drift 0 failures across 36 page pairs,
  0 broken links / 28329 anchors checked

Deslop

Deslop: claude-opus-5-thinking-high, 4 edits — unexported two internal
constants, removed the duplicate readInstall call from the first draft,
dropped the separate host-compatibility.ts catalog in favor of the existing
table, and reworded two adjacent install sentences that leaned on the deleted
claim.

Self-review

Reviewer: gpt-5.6-sol-max (change-risk-reviewer), two passes. Ten findings, all
addressed in 956f0f6d56:

1. Component-empty bundles claimed clients load skills/mcp.json — fixed:
   INSTALL.md now prints, per client, only the discovery paths the built
   bundle carries, and says so when it carries none. Both cases are tested.
2. Qoder's validator command was rendered as its install command, and an empty
   commands array rendered Install: undefined — fixed: the install
   command is first in the record, and an empty list fails the table.
3. Tier prose claimed a skills client does not read the manifest, which its
   own degraded manifest row contradicted — fixed: the line reads "loads
   its skill tree only", and a tier is now held to its paths as well as its
   rows (agent-plugins names plugin.json, skills names skills, none
   names nothing).
4. shadowedBy rendered a per-surface narrowing as whole-plugin precedence —
   fixed: it is manifest precedence only; the .mcp.json narrowing lives in
   each mcp row, and Qoder's unproven manifest-precedence row is gone.
5. A degraded surface could carry no evidence, and paths could be named with
   no discovery evidence — fixed: both are now build failures, with tests.
6. Path validation was OS-dependent — fixed: isRelocatablePosixPath, with
   a backslash-path rejection test.
7. The generated host reference rendered raw JSON, bypassing the validator —
   fixed: it renders clientCompatibilityFrom records, so an invalid record
   fails pnpm docs:site:build. Partially dismissed: no dedicated renderer
   unit test was added — the docs build runs the validator on every record and
   validator rejection is unit-tested.
8. README.md, docs/framework-mode.md, and both index.mdx locales kept the
   unsourced native-client list — fixed in all four.
9. Grok's record said local-directory install was undocumented while the pinned
   revision documents ./local-dir — fixed: the verbatim quote and a local
   install command.
10. Antigravity's none tier asserted a refusal its citation does not state —
    fixed: the manifest and skills rows are recorded as explicitly unproven.

Review threads (Codex P2, all five resolved in e94d6c56a2)

1. Install roles. install.actions is now { role, command } with roles
   install, trust, enable, verify, inspect, remove; the validator
   requires exactly one install action and INSTALL.md prints that one, so
   Qoder's validate can never be published as its install command.
2. Claims from the plan. installSurfaceEntries receives the paths the host
   projections actually planned; each client line names only its recorded paths
   that the build wrote, and says "This bundle emits none of the paths it reads"
   otherwise. A table-driven test renders all four inventories (no component,
   skills only, MCP only, both).
3. Grok. Recorded as source: marketplace with
   grok plugin install <marketplace plugin name>; the unproven local recipe is
   gone (asserted absent), and trust is its own action and its own evidence line.
4. Homepage. Both locales now describe the matrix as compatible, partial, and
   incompatible clients; the unsourced list is also gone from README.md and
   docs/framework-mode.md.
5. Per-file shadowing. shadowedBy is { path, surfaces }; only a shadow
   that takes manifest renders as replacing the plugin, and a per-surface
   shadow renders as "uses it for mcp and still reads the rest".

Also in that commit: degraded.reason is printed as a sub-bullet per narrowed
surface, and both the install prose and the generated reference state that
reading mcp.json and expanding the reserved placeholders are separate rows.

Follow-up in fba03f7cb9: shadowing files keep their authored order, because a
client that publishes a precedence order among those files publishes it in that
order (Devin: .devin-plugin/plugin.json > .claude-plugin/plugin.json > root).

Self-review round 3 (claude-fable-5-1-thinking-high and gpt-5.6-sol-max, tip d3c5362672)

Both reviewers read the diff against origin/main. Findings and disposition:

1. Shadows ignored the plan (both). Fixed: clientLine splits recorded
   precedence files into the ones this build wrote and the ones it did not. An
   emitted shadow drops the surfaces it takes from Reads: and renders as fact
   ("This build also writes .mcp.json, which it uses for mcp instead."); a file
   that takes every read surface renders as "this build also writes
   .claude-plugin/plugin.json, which it reads as the plugin instead" with no
   install command. A new test composes claude + portable and asserts exactly
   that for Devin, OpenClaw, and Qoder.
2. Marketplace wording contradicted Grok's own evidence (both). Fixed: the
   sentence is now "Install (no local-directory install is verified for this
   artifact)", mirrored in both clientsIntro strings.
3. skills tier said "skill tree only" while Qoder also reads mcp.json
   (both). Fixed: the tier renders as "loads the components it recognizes
   without reading the manifest", in the prose and both locales.
4. Grok's install action omitted --trust (Sol). Fixed: the install action
   is the documented spec verbatim (grok plugin install <name> --trust), and the
   separate trust action is /hooks-trust, the in-session command install
   cannot express.
5. Grok manifest was degraded on the basis Antigravity's is unavailable
   (Fable). Fixed: unavailable, same "unproven" reason. Tier unaffected.
6. Devin's .mcp.json was modeled as a shadow though both documents are read
   and merged (both). Fixed: the shadow is gone; mcp is degraded with the
   collision rule quoted, so the limit renders where it applies.
7. Qoder mcp and OpenClaw skills were degraded for conditions this
   artifact cannot hit (Sol). Fixed: both are supported; Qoder's precedence
   lives in its .mcp.json shadow, and OpenClaw's nested-tree limit cannot reach
   an artifact whose skill roots are always immediate children of skills/.
8. A loaded surface could omit the path it is loaded from (Sol). Fixed: a new
   validator rule binds manifest/skills/mcp to plugin.json/skills/
   mcp.json through the exported CLIENT_SURFACE_PATHS, which the renderer then
   uses to decide which surfaces a build actually wrote.
9. Install command and degraded reasons rendered unconditionally (Sol).
   Fixed: both are gated on the client reading something this build wrote — a
   componentless bundle now says "there is nothing to install there".
10. Leftover "native clients" phrasing inside the table (Fable). Fixed in
    lifecycle.uninstall.reason.
11. Untested validator rules (both). Added: empty command, local-directory
    install at tier none, non-list shadowedBy, unknown surface in a shadow,
    a loaded surface missing its path, and the shadow-order case.
12. Alphabetical shadow order discarded documented precedence (Sol). Already
    fixed in fba03f7cb9; authored order is kept.
13. No rendered-output test for the host reference (Sol) — dismissed.
    website/ has no test pool, and pnpm docs:site:build fails on an invalid
    record because it renders through the same validator. The rendered en and zh
    tables were read after the build and carry the roles, per-surface shadows, and
    degraded reasons.
14. Per-path evidence attribution (Sol) — dismissed. A single pinned
    paragraph routinely covers several paths at once (a discovery section listing
    skills/ and mcp.json together); splitting quotes per path would fragment
    the evidence without making it stronger. The rule stays "at least one dated
    note whenever any path is named".